feat: add lock / unlock functionality to `agg_bridge` for native miden assets by partylikeits1983 · Pull Request #2771 · 0xMiden/protocol

partylikeits1983 · 2026-04-14T19:28:12Z

Closes #2700. Adds a lock/unlock path for Miden-native tokens to the AggLayer bridge, mirroring PolygonZkEVMBridgeV2.claimAsset()'s handling of originNetwork == networkID.

The bridge no longer needs to be the faucet's owner to support it, so user-created faucets are now bridgeable once the bridge admin registers them via a CONFIG_AGG_BRIDGE note with is_native = true. Registration is still admin-gated (register_faucet is caller-restricted); what changed is the ownership requirement.

Approach

Native faucet branch, end-to-end:

Bridge-out: if is_native, call lock_asset → native_account::add_asset to park the asset in the bridge's own vault. No BURN note is emitted.
Bridge-in: if is_native, call unlock_and_send → native_account::remove_asset + p2id::new to emit a P2ID note to the recipient. No MINT note, no faucet ntx. PROOF_DATA_KEY is used as the serial number so the note commitment is deterministic per claim.
LET leaf construction and the existing non-native burn/mint flow are untouched.

Metadata moved to the bridge. All three FPI calls from the bridge into the faucet (asset_to_origin_asset, get_metadata_hash, get_scale) are replaced with bridge-local reads out of a new faucet_metadata_map.

A single map with four faucet-ID-keyed sub-keys holds everything:

Sub-key	Value
`[0, 0, fid_s, fid_p]`	`[addr0, addr1, addr2, addr3]`
`[1, 0, fid_s, fid_p]`	`[addr4, origin_network, scale, 0]`
`[2, 0, fid_s, fid_p]`	`[mh_lo0..3]`
`[3, 0, fid_s, fid_p]`	`[mh_hi0..3]`

faucet_registry_map is extended from [1, 0, 0, 0] to [1, is_native, 0, 0], which is backward-compatible since existing entries have is_native = 0 implicitly. CONFIG_AGG_BRIDGE carries the full metadata payload at registration (split across two calls to fit the 16-element stack).

AggLayer faucet slimmed. With metadata on the bridge, the faucet's conversion-info / metadata-hash slots and its asset_to_origin_asset / get_metadata_hash / get_scale procs are dead code. Removed: the AggLayerFaucet component now only re-exports mint_and_send + burn on top of Ownable2Step + OwnerControlled. A Miden-native faucet which wants to integrate with Agglayer, now is just a plain network fungible faucet, no AggLayer-specific storage or FPI surface needed.

Follow-ups

Not in this PR; filing separately per @bobbinth's comments in the original issue for this PR:

Collapse faucet_registry_map into faucet_metadata_map by parking is_native in sub-key 1's 4th limb. Needs a new presence check (origin-address-word non-zero) before landing.
Store the EVM token name on-chain (AggLayer: store token name in faucet storage #2585).
Verify the metadata hash on-chain (AggLayer: onchain verification of metadata hash during faucet registration #2586).

…and metadata hash

…h for native tokens

…k tests

Bumps rand 0.9.2 → 0.9.4 and rand 0.10.0 → 0.10.1 to resolve RUSTSEC-2026-0097 flagged by `cargo deny check` in CI.

Fumuran

Looks good, thank you!
It is a partial review, for now I only reviewed masm code. Mostly formatting suggestions and code optimizations

Fumuran · 2026-04-21T18:33:46Z

+#! 1. KEY [0, 0, fid_s, fid_p] -> [addr0, addr1, addr2, addr3]  (origin address part 1)
+#! 2. KEY [1, 0, fid_s, fid_p] -> [addr4, origin_network, scale, 0]  (origin address part 2)


nit: I'm not sure about fid abbreviation, it could be not immediately clear. I would vote for faucet_id_suffux and faucet_id_prefix

Fumuran · 2026-04-21T18:36:19Z

 # Offset in the local memory of the `hash_token_address` procedure
 const TOKEN_ADDR_HASH_PTR = 0

+# Local memory offsets for `register_faucet`


nit: it could be not clear whether the register_faucet is a procedure, storage slot or something else

Suggested change

# Local memory offsets for `register_faucet`

# Offsets in the local memory of the `register_faucet` procedure

Fumuran · 2026-04-21T18:38:22Z

+const REG_TOKEN_HASH_LOC = 0
+const REG_FID_S_LOC = 4
+const REG_FID_P_LOC = 5
+const REG_SCALE_LOC = 6
+const REG_ORIGIN_NETWORK_LOC = 7
+const REG_IS_NATIVE_LOC = 8


optional nit: I would use more detailed names, though it is indeed not obvious how to express these pointers clearly but briefly

Fumuran · 2026-04-21T18:44:11Z

+    movup.7 movup.7 movup.7 movup.7
+    # => [addr0, addr1, addr2, addr3, 0, 0, fid_s, fid_p, addr4, pad(11)]
+
+    swapw
+    # => [0, 0, fid_s, fid_p, addr0, addr1, addr2, addr3, addr4, pad(11)]


I believe that these lines could be removed

Fumuran · 2026-04-21T18:45:13Z

+    push.FAUCET_METADATA_MAP_SLOT[0..2]
+    exec.native_account::set_map_item
+    dropw
+    # => [addr4, pad(11)]


nit:

# => [addr4, pad(15)]

Fumuran · 2026-04-21T20:30:24Z

+    # Drop the remaining pad to start fresh
+    dropw dropw dropw
+    # => []


I'm not sure that this will work, since we are in the note script

Fumuran · 2026-04-21T20:32:30Z

+    # Pad to 16 (need 6 more zeros)
+    padw push.0.0
+    # => [0, 0, 0, 0, 0, 0, addr0, addr1, addr2, addr3, addr4, fid_s, fid_p, scale, origin_network, is_native]

-    # Load remaining origin_token_addr_[0..3] onto the stack
-    padw mem_loadw_le.ORIGIN_TOKEN_ADDR_0
-    # => [addr0, addr1, addr2, addr3, addr4, faucet_id_suffix, faucet_id_prefix, pad(13)]
+    # Move 6 pad zeros to the end
+    movdn.15 movdn.15 movdn.15 movdn.15 movdn.15 movdn.15
+    # => [addr0, addr1, addr2, addr3, addr4, fid_s, fid_p, scale, origin_network, is_native, pad(6)]


I'm not sure that this is needed

Fumuran · 2026-04-21T20:33:17Z

+    # Drop all 16 pad elements and rebuild the stack
+    dropw dropw dropw dropw
+    # => []


Same as above

Fumuran · 2026-04-21T20:33:29Z

+    # Pad to 16 (need 6 more)
+    padw push.0.0
+    # => [0, 0, 0, 0, 0, 0, fid_s, fid_p, MH_LO, MH_HI]


Fumuran · 2026-04-21T20:34:45Z

+    call.bridge_config::store_faucet_metadata_hash
    # => [pad(16)]
+
+    dropw dropw dropw dropw


I suppose this works only because we were explicitly padding to the 16 elements before call, but once everything else is updated, we should be able to remove this line

partylikeits1983 added 4 commits April 14, 2026 15:27

feat: add scale data to bridge storage

054a364

feat: update config_agg_bridge note & fix register_faucet proc

1d4feef

feat: extend faucet registration with full metadata, is_native flag, …

ea2c86d

…and metadata hash

feat: replace FPI with bridge-local reads in bridge_out, add lock pat…

7d69371

…h for native tokens

partylikeits1983 changed the title ~~feat: add scale data to bridge storage~~ feat: add lock / unlock functionality to agg_bridge for native miden assets Apr 16, 2026

mmagician added agglayer PRs or issues related to AggLayer bridging integration pr-from-maintainers PRs that come from internal contributors or integration partners. They should be given priority labels Apr 16, 2026

partylikeits1983 added 2 commits April 16, 2026 16:11

feat: add unlock path for native tokens in bridge_in, plus lock/unloc…

b3b4e96

…k tests

chore: add changelog entry & bump rand to fix cargo-deny

d1d9938

Bumps rand 0.9.2 → 0.9.4 and rand 0.10.0 → 0.10.1 to resolve RUSTSEC-2026-0097 flagged by `cargo deny check` in CI.

partylikeits1983 force-pushed the ajl-agg-bridge-lock-unlock branch from 650b79d to d1d9938 Compare April 17, 2026 17:47

partylikeits1983 mentioned this pull request Apr 20, 2026

AggLayer: Implement lock/unlock path for Miden-native tokens #2700

Open

partylikeits1983 added 2 commits April 20, 2026 12:38

refactor: slim faucet & update SPEC section

a3f8a9a

style: rustfmt import grouping

bbc919f

partylikeits1983 marked this pull request as ready for review April 20, 2026 17:27

partylikeits1983 requested review from Fumuran, bobbinth and mmagician April 20, 2026 17:27

partylikeits1983 self-assigned this Apr 20, 2026

refactor: tighten MASM stack ops, normalize stack-comment style

f0f56b5

Fumuran requested changes Apr 21, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add lock / unlock functionality to `agg_bridge` for native miden assets#2771

feat: add lock / unlock functionality to `agg_bridge` for native miden assets#2771
partylikeits1983 wants to merge 9 commits intoagglayerfrom
ajl-agg-bridge-lock-unlock

partylikeits1983 commented Apr 14, 2026 •

edited

Loading

Uh oh!

Fumuran left a comment

Uh oh!

Fumuran Apr 21, 2026

Uh oh!

Fumuran Apr 21, 2026

Uh oh!

Fumuran Apr 21, 2026

Uh oh!

Fumuran Apr 21, 2026

Uh oh!

Fumuran Apr 21, 2026

Uh oh!

Fumuran Apr 21, 2026

Uh oh!

Fumuran Apr 21, 2026

Uh oh!

Fumuran Apr 21, 2026

Uh oh!

Fumuran Apr 21, 2026

Uh oh!

Fumuran Apr 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		#! 1. KEY [0, 0, fid_s, fid_p] -> [addr0, addr1, addr2, addr3] (origin address part 1)
		#! 2. KEY [1, 0, fid_s, fid_p] -> [addr4, origin_network, scale, 0] (origin address part 2)

	# Local memory offsets for `register_faucet`
	# Offsets in the local memory of the `register_faucet` procedure

Conversation

partylikeits1983 commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Approach

Follow-ups

Uh oh!

Fumuran left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

partylikeits1983 commented Apr 14, 2026 •

edited

Loading